package woogieunit.annotations;
import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.lang.annotation.ElementType;


/**
 * Describes a method which will scale the "difficulty" of its return value with respect 
 * to a given input value, which is an integer >= 1.
 * A scaling method which is meant to scale a single parameter of a targetted benchmark must have a 
 * signature as follows: Object methodName(int difficulty). A scaling method which is meant to scale 
 * all parameters of a targetted benchmark must have the following signature, even if there is only 
 * one targetted benchmark parameter: Object[] methodName(int difficulty). An exception will be thrown 
 * if a method described as a ScalingMethod does not match the required signature.
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@Documented
public @interface ScalingMethod {
	/**
	 * Unique name for this ScalingMethod - is referenced by the annotation Scales
	 * @return
	 */
	String name();
	/**
	 * The maximum acceptable input value for difficulty (this <u>must</u> be set, and must be 
	 * less than Integer.MAX_INT and greater than 1)
	 * @return
	 */
	int maxNumberOfCalls();
	/**
	 * Suggestion of minimum number of calls to be made to provide meaningful data. Can be 
	 * overridden.
	 * @return
	 */
	int minNumberOfCalls() default 1;
	/**
	 * Suggestion that all possible difficulty values be used. If a scaling method is used which 
	 * is non-linear (ie it tests corner cases, or for potentially troublesome input), this should 
	 * be set to false
	 * @return
	 */
	boolean linearScaling() default true; 
}
